1   /*
2    * Copyright (C) 2007 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.collect.testing;
18  
19  import com.google.common.annotations.GwtCompatible;
20  
21  import java.util.Collections;
22  import java.util.Iterator;
23  
24  /**
25   * A utility for testing an Iterator implementation by comparing its behavior to
26   * that of a "known good" reference implementation. In order to accomplish this,
27   * it's important to test a great variety of sequences of the
28   * {@link Iterator#next}, {@link Iterator#hasNext} and {@link Iterator#remove}
29   * operations. This utility takes the brute-force approach of trying <i>all</i>
30   * possible sequences of these operations, up to a given number of steps. So, if
31   * the caller specifies to use <i>n</i> steps, a total of <i>3^n</i> tests are
32   * actually performed.
33   *
34   * <p>For instance, if <i>steps</i> is 5, one example sequence that will be
35   * tested is:
36   *
37   * <ol>
38   * <li>remove();
39   * <li>hasNext()
40   * <li>hasNext();
41   * <li>remove();
42   * <li>next();
43   * </ol>
44   *
45   * <p>This particular order of operations may be unrealistic, and testing all 3^5
46   * of them may be thought of as overkill; however, it's difficult to determine
47   * which proper subset of this massive set would be sufficient to expose any
48   * possible bug. Brute force is simpler.
49   *
50   * <p>To use this class the concrete subclass must implement the
51   * {@link IteratorTester#newTargetIterator()} method. This is because it's
52   * impossible to test an Iterator without changing its state, so the tester
53   * needs a steady supply of fresh Iterators.
54   *
55   * <p>If your iterator supports modification through {@code remove()}, you may
56   * wish to override the verify() method, which is called <em>after</em>
57   * each sequence and is guaranteed to be called using the latest values
58   * obtained from {@link IteratorTester#newTargetIterator()}.
59   *
60   * @author Kevin Bourrillion
61   * @author Chris Povirk
62   */
63  @GwtCompatible
64  public abstract class IteratorTester<E> extends
65      AbstractIteratorTester<E, Iterator<E>> {
66    /**
67     * Creates an IteratorTester.
68     *
69     * @param steps how many operations to test for each tested pair of iterators
70     * @param features the features supported by the iterator
71     */
72    protected IteratorTester(int steps,
73        Iterable<? extends IteratorFeature> features,
74        Iterable<E> expectedElements, KnownOrder knownOrder) {
75      super(steps, Collections.<E>singleton(null), features, expectedElements,
76          knownOrder, 0);
77    }
78  
79    @Override
80    protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() {
81      return iteratorStimuli();
82    }
83  }